/*
 * Copyright (C) 2008-2011 CBDP Consortium
 * 
 * All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.
 * 
 * This software consists of contributions made by many individuals, 
 * listed below:
 *
 * Author: 	Xabier Laiseca <xabier.laiseca@deusto.es>
 * 			David Ausín <david.ausin@deusto.es>
 */
package cbdp.server.contextreasoner;

import java.io.InputStream;
import java.util.Collection;
import java.util.Map;

import cbdp.server.contextreasoner.exceptions.ContextManagerException;
import cbdp.server.contextreasoner.model.Instance;
import cbdp.server.contextreasoner.model.exceptions.NotExistingInstanceException;

/**
 * The <code>ContextManager</code> handles the CBDP's ontology. It offers methods to extend the ontology and to manage its instances.
 * @author Xabier Laiseca (University of Deusto)
 *
 */
public interface ContextManagerWithoutExecutionSupport
{
	public final static String CONTEXT_MANAGER_NAME_PROPERTY_NAME = "cm.name";
	public final static String CONTEXT_MANAGER_SUPPORTS_TRANSACTIONS_PROPERTY_NAME = "cm.support.transactions";
	
	public Map<String, String> getOntologyURIs();
	
	/**
	 * Extends the core ontology with a new ontology.
	 * @param ontology a InputStream that contains the ontology schema to add to the context.
	 * @param namespace the base namespace of the extension of the ontology
	 * @throws ContextManagerException thrown when the ontology can not be extended.
	 * @throws IllegalArgumentException thrown when the <code>namespace</code> is not a valid URI
	 */
	@Deprecated
	public void extendOntology(final InputStream ontology, final String namespace) throws ContextManagerException;
	
	/**
	 * Extends the core ontology with a new ontology.
	 * @param ontology a InputStream that contains the ontology schema to add to the context.
	 * @param namespace the base namespace of the extension of the ontology
	 * @throws ContextManagerException thrown when the ontology can not be extended.
	 * @throws IllegalArgumentException thrown when the <code>namespace</code> is not a valid URI
	 */
	public void extendOntology(final InputStream ontology, final String namespace, final String ontologyName) throws ContextManagerException;
	
	/**
	 * Creates a new instance in the ontology.
	 * @param id the identifier of the instance to add.
	 * @param type the type of the instance to create.
	 * @throws ContextManagerException thrown when the instance can not be added.
	 * @throws IllegalArgumentException thrown when the <code>id</code> is not a valid URI.
	 */	
	public void createInstance(final String id, final String type) throws ContextManagerException;
	
	/**
	 * Deletes an instance from the ontology.
	 * @param id the identifier of the instance to delete.
	 * @throws ContextManagerException thrown when the instance can not be deleted.
	 * @throws NotExistingInstanceException thrown when the instance does not exist.
	 * @throws IllegalArgumentException thrown when the <code>id</code> is not a valid URI.
	 */
	public void deleteInstance(final String id) throws ContextManagerException, NotExistingInstanceException;
	
	
	/**
	 * Returns an instance of the ontology.
	 * @param id the identifier of hte instance.
	 * @return an instance of the ontology.
	 * @throws ContextManagerException thrown when the instance does not exist.
	 * @throws NotExistingInstanceException thrown when the instance does not exist.
	 * @throws IllegalArgumentException thrown when the <code>id</code> is not a valid URI.
	 */
	public Instance getInstance(final String id) throws ContextManagerException, NotExistingInstanceException;
	
	/**
	 * Returns an instance of the ontology. The instance is created if it does not exist.
	 * @param id the identifier of hte instance.
	 * @param type the type of the instance to create if required.
	 * @return an instance of the ontology.
	 * @throws ContextManagerException thrown when the instance does not exist.
	 * @throws IllegalArgumentException thrown when the <code>id</code> is not a valid URI.
	 */
	public Instance getInstance(final String id, final String type) throws ContextManagerException;
	
	/**
	 * Returns a <code>Collection</code> of instances of a class from the ontology.
	 * @param clazz the class to get the instances.
	 * @return a <code>Collection</code> of instances of a class from the ontology.
	 * @throws ContextManagerException thrown when the class does not exist.
	 * @throws IllegalArgumentException thrown when the <code>clazz</code> is not a valid URI.
	 */
	public Collection<Instance> getInstances(final String clazz) throws ContextManagerException;
}
